home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / other / wla_020_3.0 / wla.txt < prev    next >
Text File  |  2000-02-28  |  32KB  |  1,116 lines
  1.  
  2. ------------------------------------------------------------------------------
  3.      WLA GB-Z80 Macro Assembler v3.0 Copyright 1998-2000 by Ville Helin
  4. ------------------------------------------------------------------------------
  5.  
  6.  
  7. 1..... Introduction
  8. 2..... WLA History
  9. 3..... WLALINK History
  10. 4..... Assembler Directives
  11. 5..... Assembler Syntax
  12.  5.1.. Case Sensitivity
  13.  5.2.. Comments
  14.  5.3.. Labels
  15.  5.4.. Number Types
  16.  5.5.. Strings
  17.  5.6.. Supported GB-Z80 Commands
  18. 6..... Error Messages
  19. 7..... Supported Types
  20.  7.1.. ROM Size
  21.  7.2.. RAM Size
  22.  7.3.. Cartridge Type
  23. 8..... Bugs
  24. 9..... Files
  25.  9.1.. 'features_test.s'
  26.  9.2.. 'gb_hardware.i'
  27.  9.3.. 'cgb_hardware.i'
  28.  9.4.. 'nintendo_logo.i'
  29.  9.5.. 'pocket_voice.i'
  30. 10.... Temporary Files
  31. 11.... Compiling
  32.  11.1. Compiling ROM Images
  33.  11.2. Compiling Object Files
  34.  11.3. Compiling Compact Object Files
  35.  11.4. Compiling Library Files
  36.  11.5. Compiling Compact Library Files
  37. 12.... Linking
  38. 13.... Pocket Voice
  39. 14.... Author
  40. 15.... Thanks
  41. 16.... Future
  42. 17.... Support
  43. 18.... Legal Note
  44.  
  45.  
  46.  
  47. ------------------------------------------------------------------------------
  48. 1... Introduction
  49. ------------------------------------------------------------------------------
  50.  
  51.  
  52. Here is yet another macro assembler to help you to produce Game Boy software.
  53.  
  54. I wrote this because I had never written an assembler before and I really
  55. needed a macro assembler which could compile the GB-Z80 code I wrote. ;)
  56.  
  57. This is my ideal GB-Z80 macro assembler (not in final form, not yet). ;)
  58. Tastes differ. Thus WLA!
  59.  
  60. I will not release WLA's source code, not now, as it is ugly, and would
  61. put me into shame. ;) Any comments are gladly accepted. And if you produce
  62. nice software with WLA, send me mail about it (or even the whole programme)!
  63. ;)
  64.  
  65.  
  66.  
  67. ------------------------------------------------------------------------------
  68. 2... WLA History
  69. ------------------------------------------------------------------------------
  70.  
  71.  
  72. v3.0 (20-Feb-2000) Added support for "LDH (x), A", "LDH A, (x)",
  73.                      "LD (HLI), A", "LD (HL+), A", "LD A, (HLI)",
  74.                      "LD A, (HL+)", "LD (HLD), A", LD (HL-), A",
  75.                      "LD A, (HLD)" and "LD A, (HL-)".
  76.                    WLA filters away unreferenced local lables in
  77.                      object/library output mode.
  78.                    MSDOS temporary file directory is now the working
  79.                      directory.
  80.                    Added "-co" -option for compact object file producing.
  81.                    Added "-cl" -option for compact library file producing.
  82.                    Enhanced .SECTION logic (syntax changed!).
  83.                    Added new error messages.
  84.                    Optimized temporary file usage.
  85.                    Optimized directive decoding.
  86.                    Optimized internal pass 2.
  87.                    Optimized .SECTION handling.
  88.                    Optimized .DSB and .DSW.
  89.                    Optimized pass 1.
  90.                    Optimized .INCLUDE.
  91.  
  92. v2.9 (16-Feb-2000) Section names with spaces crashed WLA.
  93.                    Fixed address bound checking in .BANK.
  94.                    Added more error messages.
  95.  
  96. v2.8 (15-Feb-2000) Added .EXPORT.
  97.                    All strings starting with "." are treated as directives.
  98.                    Directives are not case sensitive any more.
  99.                    Fixed a broken 0x0D filter (in MSDOS text files).
  100.                    Source file ending into a comment could crash WLA.
  101.                    Optimized .INCLUDE.
  102.                    Libraries can now have references outside.
  103.                    Amiga object/library files were not compatible with
  104.                      PC files.
  105.                    Fixed a bug in object file generator that could crash WLA.
  106.  
  107. v2.7 (07-Feb-2000) WLA returns 0 when help information is displayed.
  108.                    WLA returns 1 when execution ended in error. -1 produced
  109.                      ugly error messages on Amiga computers.
  110.                    WLA gives now an error when the user tries to produce
  111.                      a library file which has references to outside.
  112.                    Amiga version has version string.
  113.                    Enhanced some error messages.
  114.                    Enhanced documents.
  115.  
  116. v2.6 (03-Feb-2000) PC relative reference distances inside sections could be
  117.                      more than 127 bytes.
  118.  
  119. v2.5 (29-Jan-2000) Enhanced documents.
  120.                    Fixed GBC indicator from $C0 to $80.
  121.  
  122. v2.4 (26-Jan-2000) Fixed a typo "NET NC" to "RET NC".
  123.                    Enhanced some error messages.
  124.                    Added .ROMGBC, .ROMDMG and .ROMSGB.
  125.                    Rewriting memory with equal data doesn't give an error.
  126.  
  127. v2.3 (23-Jan-2000) Added .SECTION, .ENDS.
  128.                    Added "-l" -option for library file producing.
  129.                    Fixed address calculations a little more.
  130.                    WLA returns -1 when execution ended in error.
  131.                    Local labels are now local to sections or object file.
  132.                    Enhanced the documents.
  133.  
  134. v2.2 (16-Jan-2000) Added .DSW, .DW, .ENUM and .ENDE.
  135.  
  136. v2.1 (14-Jan-2000) Added $BE (Pocket Voice) to supported cartridge types.
  137.                    Added "-v" -option for verbose information displaying.
  138.                    Optimized pass 1.
  139.                    Fixed possible errors in address calculations.
  140.  
  141. v2.0 (12-Jan-2000) Enhanced the documents.
  142.                    Optimized internal pass 2 and directive including.
  143.                    Fixed overflow check (in .ORG).
  144.                    Added "-o" -option for object file producing.
  145.                    Added linker executable "wlalink".
  146.                    Added .INCDIR.
  147.  
  148. v1.9 (06-Jan-2000) Optimized .INCBIN, .INCLUDE and internal passes
  149.                     1 and 2.
  150.  
  151. v1.8 (23-Dec-1999) Enhanced the documents.
  152.                    Fixed overflow checker once again. Every bank gained one
  153.                     byte more (total 16384).
  154.  
  155. v1.7 (04-Dec-1999) Enhanced the documents.
  156.                    Added gb_hardware.i.
  157.                    .INCBIN didn't free buffer memory.
  158.                    Optimized .INCBIN.
  159.                    .INCBIN now caches all the files.
  160.                    Optimized internal passes 1 and 2.
  161.                    Linux version is optimized for 486.
  162.  
  163. v1.6 (14-Nov-1999) Enhanced the documents.
  164.                    Fixed nintendo_logo.i so it works on a real Game Boy.
  165.                    Fixed complement check calculation to work.
  166.                    Overflow checker thought GB ROM banks were 8KB each!
  167.                     Fixed to 16KB. Ville no baka!
  168.                    Added .REPT.
  169.                    Added .ENDR.
  170.  
  171. v1.5 (10-Jun-1999) Enhanced the documents.
  172.                    WLA does now one pass to the input data and
  173.                     two passes to the internal data.
  174.  
  175. v1.4 (25-May-1999) Renamed nintendo_logo.s to nintendo_logo.i.
  176.                    Fixed nintendo_logo.i Wzonka-Lad-compatible.
  177.                    Fixed pass-texts, as WLA does actually one pass,
  178.                     three of the old ones were made to the WLA's internal data.
  179.                    Added one funky new optcode, "DEBUG", which will
  180.                     translate to $ED (unused in GB-Z80). This one will
  181.                     flash the power light when executed on Wzonka-Lad,
  182.                     my Game Boy emulator. Use it only for debugging!
  183.  
  184. v1.3 (01-Jan-1999) Enhanced the documents.
  185.                    WLA now shows the unused areas of the ROM file after
  186.                     a successful compile in hexadecimal format.
  187.                    Many WLA directives accepted non-pure values, not anymore.
  188.                    Added .DSB.
  189.                    .DB handles now strings as well.
  190.  
  191. v1.2 (21-Dec-1998) Enhanced the documents.
  192.                    Added a list ("gb-z80.txt") of the supported GB-Z80 commands
  193.                     to the archive.
  194.                    Free strings don't break the compile loop anymore.
  195.                    Added .INCBIN.
  196.  
  197. v1.1 (13-Dec-1998) Enhanced the documents.
  198.                    Removed an unused function.
  199.                    Number input now detects and discards numbers from
  200.                     outside the word boundaries.
  201.                    WLA now shows the unused areas of the ROM file after
  202.                     a successful compile.
  203.                    Added .IFNDEF.
  204.                    Added .IFDEF.
  205.                    Added .ELSE.
  206.                    Added .ENDIF.
  207.                    Added @@@ to .MACRO.
  208.                    .DB accepted values from outside the byte boundaries.
  209.  
  210. v1.0 (12-Dec-1998) The first public release.
  211.  
  212.  
  213.  
  214. ------------------------------------------------------------------------------
  215. 3... WLALINK History
  216. ------------------------------------------------------------------------------
  217.  
  218.  
  219. v1.8 (20-Feb-2000) The supported file formats are only "WLAN" and "WLA4".
  220.                    WLALINK uses now less memory.
  221.                    Enhanced some error messages.
  222.  
  223. v1.7 (15-Feb-2000) Added support for WLA's .EXPORT.
  224.                    Enhanced some error messages.
  225.                    Optimized ROM file generation.
  226.                    The supported file formats are only "WLAM" and "WLA3".
  227.                    Amiga object/library files were not compatible with
  228.                      PC files.
  229.  
  230.  
  231. v1.6 (07-Feb-2000) WLALINK returns 0 when help information is displayed.
  232.                    Amiga version has version string.
  233.  
  234. v1.5 (03-Feb-2000) PC relative reference distances inside sections could be
  235.                      more than 127 bytes.
  236.                    Enhanced some error messages.
  237.  
  238. v1.4 (31-Jan-2000) Duplicate labels positioned in different places in Game
  239.                      Boy memory map break the linking loop.
  240.                    Fixed object identifier, verbose mode screwed up the names.
  241.                    Enhanced some error messages.
  242.                    Referencing to a label inside a section more than once
  243.                      screwed up the label's address.
  244.  
  245. v1.3 (26-Jan-2000) Rewriting memory with equal data doesn't give an error.
  246.                    Enhanced some error messages.
  247.  
  248. v1.2 (23-Jan-2000) Added support for library files.
  249.  
  250. v1.1 (14-Jan-2000) Added support for Pocket Voice.
  251.                    Added "-v" -option for verbose information displaying.
  252.                    WLALINK now checks the object file formats.
  253.  
  254. v1.0 (12-Jan-2000) The first public release.
  255.  
  256.  
  257.  
  258. ------------------------------------------------------------------------------
  259. 4... Assembler Directives
  260. ------------------------------------------------------------------------------
  261.  
  262.  
  263. The directives are collected as they appear. Group 2 directives take place 
  264. as they are found. Group 1 directives are applied at the very end, after
  265. all the code has been processed, where they overwrite the actual code.
  266.  
  267. Here are the supported directives (with examples) in WLA:
  268.  
  269. Group 1:
  270.  
  271. .NAME = "NAME OF THE ROM"
  272. .ROMSIZE = 0
  273. .RAMSIZE = 0
  274. .EMPTYFILL = $C9
  275. .CARTRIDGETYPE = 1
  276. .LICENSEECODEOLD = $1A
  277. .LICENSEECODENEW = "1A"
  278. .COMPUTECHECKSUM
  279. .COMPUTECOMPLEMENTCHECK
  280. .ROMGBC
  281. .ROMDMG
  282. .ROMSGB
  283. .EXPORT work_x
  284.  
  285. Group 2:
  286.  
  287. .INCDIR "/usr/programming/gb/include/"
  288. .INCLUDE "cgb_hardware.i"
  289. .INCBIN "sorority.bin"
  290. .MACRO TEST
  291. .ENDM
  292. .BANK = 0
  293. .ORG = $150
  294. .DSB 256 $10
  295. .DSW 128 20
  296. .DB 100 $30 %1000 "HELLO WORLD!"
  297. .DW 16000 10 255
  298. .DEFINE IF $FF0F
  299. .IFDEF IF
  300. .IFNDEF IF
  301. .ELSE
  302. .ENDIF
  303. .REPT 6
  304. .ENDR
  305. .ENUM $C000
  306. .ENDE
  307. .SECTION "Init" FORCE
  308. .ENDS
  309.  
  310.  
  311. Descriptions:
  312.  
  313. -------------------------
  314. .NAME = "NAME OF THE ROM"
  315. -------------------------
  316.  
  317. Fills the 16 bytes ranging from $134 to $143 with the provided string.
  318. If the string is shorter than 16 bytes the remaining space is filled with $00.
  319.  
  320. This is not a compulsory directive.
  321.  
  322. ------------
  323. .ROMSIZE = 0
  324. ------------
  325.  
  326. Indicates the size of the ROM. This is a standard GB ROM size indicator value
  327. found at $148 in a GB ROM, and there this one is put to also.
  328.  
  329. This is a compulsory directive.
  330.  
  331. ------------
  332. .RAMSIZE = 0
  333. ------------
  334.  
  335. Indicates the size of the RAM. This is a standard GB RAM size indicator value
  336. found at $149 in a GB ROM, and there this one is put to also.
  337.  
  338. This is a compulsory directive.
  339.  
  340. ----------------
  341. .EMPTYFILL = $C9
  342. ----------------
  343.  
  344. This byte is used in filling the unused areas of the ROM file. EMPTYFILL
  345. defaults to $00.
  346.  
  347. This is not a compulsory directive.
  348.  
  349. ------------------
  350. .CARTRIDGETYPE = 1
  351. ------------------
  352.  
  353. Indicates the type of the cartridge (mapper and so on). This is a standard
  354. GB cartridge type indicator value found at $147 in a GB ROM, and there this
  355. one is put to also.
  356.  
  357. This is not a compulsory directive.
  358.  
  359. ----------------------
  360. .LICENSEECODEOLD = $1A
  361. ----------------------
  362.  
  363. This is a standard old licensee code found at $14B in a GB ROM, and there this
  364. one is put to also. .LICENSEECODEOLD cannot be defined with .LICENSEECODENEW.
  365.  
  366. This is not a compulsory directive.
  367.  
  368. -----------------------
  369. .LICENSEECODENEW = "1A"
  370. -----------------------
  371.  
  372. This is a standard new licensee code found at $144 and $145 in a GB ROM, and
  373. there this one is put to also. .LICENSEECODENEW cannot be defined with
  374. .LICENSEECODEOLD. $33 is inserted into $14B, as well.
  375.  
  376. This is not a compulsory directive.
  377.  
  378. ----------------
  379. .COMPUTECHECKSUM
  380. ----------------
  381.  
  382. When this directive is used WLA computes the ROM checksum found at $14E and
  383. $14F in a GB ROM.
  384.  
  385. This is not a compulsory directive.
  386.  
  387. -----------------------
  388. .COMPUTECOMPLEMENTCHECK
  389. -----------------------
  390.  
  391. When this directive is used WLA computes the ROM complement check found at
  392. $14D in a GB ROM.
  393.  
  394. This is not a compulsory directive, but very recommended. ;)
  395.  
  396. --------------------------------------
  397. .INCDIR "/usr/programming/gb/include/"    
  398. --------------------------------------
  399.  
  400. Changes the current include root directory. Use this to specify main
  401. directory for the following .INCLUDE and .INCBIN directives.
  402.  
  403. This is not a compulsory directive.
  404.  
  405. -------------------------
  406. .INCLUDE "cgb_hardware.i"
  407. -------------------------
  408.  
  409. Includes the specified file to the source file.
  410.  
  411. This is not a compulsory directive.
  412.  
  413. ----------------------
  414. .INCBIN "sorority.bin"
  415. ----------------------
  416.  
  417. Includes the specified data file into the source file. .INCBIN caches
  418. all files into memory, so you can .INCBIN any data file millions of
  419. times, but it is loaded only once.
  420.  
  421. This is not a compulsory directive.
  422.  
  423. -----------
  424. .MACRO TEST
  425. -----------
  426.  
  427. Begins a macro called 'TEST'. Macro text size is at max 1024 bytes.
  428.  
  429. You can use '@@@' inside a macro to eg. separate a label from the other
  430. macro 'TEST' occurrences. Take a look at the supplied source code
  431. 'features_test.s' for more information. You can use a macro with '@@@' at
  432. max 1000 times. '@@@' is converted to an integer ranging from 0 to 999 at
  433. compile time.
  434.  
  435. This is not a compulsory directive.
  436.  
  437. -----
  438. .ENDM
  439. -----
  440.  
  441. Ends the macro.
  442.  
  443. This is not a compulsory directive, but when .MACRO is used this one is
  444. required to terminate it.
  445.  
  446. ---------
  447. .BANK = 0
  448. ---------
  449.  
  450. Selects the ROM bank.
  451.  
  452. This is a compulsory directive.
  453.  
  454. -----------
  455. .ORG = $150
  456. -----------
  457.  
  458. Selects the starting address. The value supplied here is relative to the
  459. ROM bank given with .BANK.
  460.  
  461. This is a compulsory directive.
  462.  
  463. ------------
  464. .DSB 256 $10
  465. ------------
  466.  
  467. Defines 256 bytes of $10.
  468.  
  469. This is not a compulsory directive.
  470.  
  471. -----------
  472. .DSW 128 20
  473. -----------
  474.  
  475. Defines 128 words (two bytes) of 20.
  476.  
  477. This is not a compulsory directive.
  478.  
  479. --------------------------------
  480. .DB 100 $30 %1000 "HELLO WORLD!"
  481. --------------------------------
  482.  
  483. Defines bytes.
  484.  
  485. This is not a compulsory directive.
  486.  
  487. ----------------
  488. .DW 16000 10 255
  489. ----------------
  490.  
  491. Defines words (two bytes each). .DW takes only numbers and
  492. characters as input, not strings.
  493.  
  494. This is not a compulsory directive.
  495.  
  496. ----------------
  497. .DEFINE IF $FF0F
  498. ----------------
  499.  
  500. Assigns a number to a string. This is all it can do, nothing else.
  501. Defined strings can only be found amid the GB-Z80 code.
  502.  
  503. This is not a compulsory directive.
  504.  
  505. ---------
  506. .IFDEF IF
  507. ---------
  508.  
  509. If "IF" is defined, then the following piece of code is acknoledged
  510. until .ENDIF occurs in the text, unless it is skipped.
  511.  
  512. This is not a compulsory directive.
  513.  
  514. ----------
  515. .IFNDEF IF
  516. ----------
  517.  
  518. If "IF" is not defined, then the following piece of code is acknoledged
  519. until .ENDIF occurs in the text, unless it is skipped.
  520.  
  521. This is not a compulsory directive.
  522.  
  523. -----
  524. .ELSE
  525. -----
  526.  
  527. If the previous .IFDEF or .IFNDEF failed then the following text until
  528. .ENDIF is acknoledged.
  529.  
  530. This is not a compulsory directive.
  531.  
  532. ------
  533. .ENDIF
  534. ------
  535.  
  536. This terminates any .IFDEF or .IFNDEF directive.
  537.  
  538. This is not a compulsory directive, but if you use .IFDEF or .IFNDEF then
  539. you need also to apply this.
  540.  
  541. -------
  542. .REPT 6
  543. -------
  544.  
  545. Repeats the text enclosed between ".REPT x" and ".ENDR" x times (6 in
  546. this example). Repetition text size is at max 1024 bytes.
  547.  
  548. This is not a compulsory directive.
  549.  
  550. -----
  551. .ENDR
  552. -----
  553.  
  554. Ends the repetition.
  555.  
  556. This is not a compulsory directive, but when .REPT is used this one is
  557. required to terminate it.
  558.  
  559. -----------
  560. .ENUM $C000
  561. -----------
  562.  
  563. Starts enumeration from $C000. Very useful for defining variables.
  564. Here's an example:
  565.  
  566. ...
  567. .ENUM $A000
  568. _scroll_x DB
  569. _scroll_y DB
  570. player_x  DW
  571. player_y  DW
  572. map_01    DS 1024
  573. map_02    DS 2048
  574. .ENDE
  575. ...
  576.  
  577. Previous example transforms into following definitions:
  578.  
  579. .DEFINE _scroll_x $A000
  580. .DEFINE _scroll_y $A001
  581. .DEFINE player_x  $A002
  582. .DEFINE player_y  $A004
  583. .DEFINE map_01    $A006
  584. .DEFINE map_02    $A406
  585.  
  586. This is not a compulsory directive.
  587.  
  588. -----
  589. .ENDE
  590. -----
  591.  
  592. Ends the enumeration.
  593.  
  594. This is not a compulsory directive, but when .ENUM is used this one is
  595. required to terminate it.
  596.  
  597. ---------------------
  598. .SECTION "Init" FORCE
  599. ---------------------
  600.  
  601. Begins a section called "Init". Before a section can be declared, .BANK
  602. and .ORG must be used. .BANK tells the bank number where this section
  603. will be later relocated into. .ORG tells the offset for the relocation
  604. from the beginning of .BANK.
  605.  
  606. FORCE after the name of the section tells WLA that the section _must_ be
  607. inserted so it starts at .ORG. FORCE can be replaced with FREE which
  608. means that the section can be inserted somewhere, where there is room,
  609. but after .ORG inside the .BANK.
  610.  
  611. Here's an example:
  612.  
  613. ...
  614. .BANK 0
  615. .ORG $150
  616. .SECTION "Init" FREE
  617.         DI
  618.         LD      SP, $FFFE
  619.         SUB     A
  620.         LD      ($FF00+R_IE), A
  621. .ENDS
  622. ...
  623.  
  624. This tells WLA that a section called "Init" must be located somewhere in
  625. bank 0, but not $0-$14F.
  626.  
  627. This is not a compulsory directive.
  628.  
  629. -----
  630. .ENDS
  631. -----
  632.  
  633. Ends the section.
  634.  
  635. This is not a compulsory directive, but when .SECTION is used this one is
  636. required to terminate it.
  637.  
  638. -------
  639. .ROMGBC
  640. -------
  641.  
  642. Inserts data into the specific ROM location to mark the ROM as a GBC ROM
  643. ($C0 -> $0143, so ROM name is max. 15 characters long).
  644.  
  645. This is not a compulsory directive.
  646.  
  647. -------
  648. .ROMDMG
  649. -------
  650.  
  651. Inserts data into the specific ROM location to mark the ROM as a DMG ROM
  652. ($00 -> $0146).
  653.  
  654. This is not a compulsory directive. .ROMDMG cannot be used with .ROMSGB.
  655.  
  656.  
  657. -------
  658. .ROMSGB
  659. -------
  660.  
  661. Inserts data into the specific ROM location to mark the ROM as a SGB enhanced
  662. ROM ($03 -> $0146).
  663.  
  664. This is not a compulsory directive. .ROMSGB cannot be used with .ROMDMG.
  665.  
  666. --------------
  667. .EXPORT work_x
  668. --------------
  669.  
  670. Exports the definition "work_x" to outside. .EXPORT can only be used inside
  671. object and library files. Exported definitions are visible to all object files
  672. and libraries in the linking procedure.
  673.  
  674.  
  675.  
  676. ------------------------------------------------------------------------------
  677. 5... Assembler Syntax
  678. ------------------------------------------------------------------------------
  679.  
  680.  
  681. 5.1. Case Sensitivity
  682.  
  683. WLA is case sensitive, so be careful. But note that directives are not case
  684. sensitive.
  685.  
  686.  
  687. 5.2. Comments
  688.  
  689. Comments begin with ';' and end along with the line.
  690.  
  691.  
  692. 5.3. Labels
  693.  
  694. Labels are ordinary strings that end to ':'. Labels starting with "_"
  695. are considered as local labels and do not show outside sections where
  696. they were defined, or outside object files, if they were not defined
  697. inside a section.
  698.  
  699.  
  700. 5.4. Number Types
  701.  
  702. You can't use arithmetic or logic expressions, all values must be precomputed.
  703.  
  704. 1000 - decimal.
  705. $100 - hexadecimal.
  706. %100 - binary.
  707. 'x'  - character.
  708.  
  709.  
  710. 5.5. Strings
  711.  
  712. Strings begin and end to '"'. Note that no 0 is inserted to indicate the
  713. termination of the string like in eg. C. You'll have to do it yourself.
  714.  
  715.  
  716. 5.6. Supported GB-Z80 commands
  717.  
  718. Check out the file "z80.txt" coming in this archive.
  719.  
  720. Additionally there is a command called "DEBUG" which will translate to
  721. $ED. This one is not used in real GB-Z80, but my Game Boy emulator,
  722. Wzonka-Lad, will invert the power light mode when $ED is executed.
  723.  
  724. Don't use DEBUG if you are going to use your code elsewhere!
  725.  
  726.  
  727.  
  728. ------------------------------------------------------------------------------
  729. 6... Error Messages
  730. ------------------------------------------------------------------------------
  731.  
  732.  
  733. There are quite a few of them in WLA, but most of them are not as informative
  734. as I would like them to be. This will be fixed in the future. Mean while, be
  735. careful. ;)
  736.  
  737.  
  738.  
  739. ------------------------------------------------------------------------------
  740. 7... Supported Types
  741. ------------------------------------------------------------------------------
  742.  
  743.  
  744. 7.1. ROM Size
  745.  
  746.  $0 - 256Kbit =  32KByte =   2 banks
  747.  $1 - 512Kbit =  64KByte =   4 banks
  748.  $2 -   1Mbit = 128KByte =   8 banks
  749.  $3 -   2Mbit = 256KByte =  16 banks
  750.  $4 -   4Mbit = 512KByte =  32 banks
  751.  $5 -   8Mbit =   1MByte =  64 banks
  752.  $6 -  16Mbit =   2MByte = 128 banks
  753. $52 -   9Mbit = 1.1MByte =  72 banks
  754. $53 -  10Mbit = 1.2MByte =  80 banks
  755. $54 -  12Mbit = 1.5MByte =  96 banks
  756.  
  757.  
  758. 7.2. RAM Size
  759.  
  760.  $0 -    None
  761.  $1 -  16kbit =   2kByte =   1 bank
  762.  $2 -  64kbit =   8kByte =   1 bank
  763.  $3 - 256kbit =  32kByte =   4 banks
  764.  $4 -   1Mbit = 128kByte =  16 banks
  765.  
  766.  
  767. 7.3. Cartridge Type
  768.  
  769. It's up to the user to check that the cartridge type is valid and
  770. can be used combined with the supplied ROM and RAM sizes.
  771.  
  772. Here's a list of what the value can be:
  773.  
  774.  $0 - ROM ONLY
  775.  $1 - ROM+MBC1
  776.  $2 - ROM+MBC1+RAM
  777.  $3 - ROM+MBC1+RAM+BATT
  778.  $5 - ROM+MBC2
  779.  $6 - ROM+MBC2+BATTERY
  780.  $8 - ROM+RAM
  781.  $9 - ROM+RAM+BATTERY
  782.  $B - ROM+MMM01
  783.  $C - ROM+MMM01+SRAM
  784.  $D - ROM+MMM01+SRAM+BATT
  785.  $F - ROM+MBC3+TIMER+BATT
  786. $10 - ROM+MBC3+TIMER+RAM+BATT
  787. $11 - ROM+MBC3
  788. $12 - ROM+MBC3+RAM
  789. $13 - ROM+MBC3+RAM+BATT
  790. $19 - ROM+MBC5
  791. $1A - ROM+MBC5+RAM
  792. $1B - ROM+MBC5+RAM+BATT
  793. $1C - ROM+MBC5+RUMBLE
  794. $1D - ROM+MBC5+RUMBLE+SRAM
  795. $1E - ROM+MBC5+RUMBLE+SRAM+BATT
  796. $1F - Pocket Camera
  797. $BE - Pocket Voice
  798. $FD - Bandai TAMA5
  799. $FE - Hudson HuC-3
  800. $FF - Hudson HuC-1
  801.  
  802.  
  803.  
  804. ------------------------------------------------------------------------------
  805. 8... Bugs
  806. ------------------------------------------------------------------------------
  807.  
  808.  
  809. If you find bugs, please let me know asap. Anything, small or big, send
  810. me mail!
  811.  
  812.  
  813.  
  814. ------------------------------------------------------------------------------
  815. 9... Files
  816. ------------------------------------------------------------------------------
  817.  
  818.  
  819. 9.1. 'features_test.s'
  820.  
  821. 'features_test.s' shows how to use most of the WLA's directives and a
  822. little of the GB-Z80 syntax itself.
  823.  
  824. The program it describes is supposed to change the background color, so it
  825. doesn't do really anything fantastic. ;)
  826.  
  827.  
  828. 9.2. 'gb_hardware.i'
  829.  
  830. 'gb_hardware.i' has all the Game Boy hardware register names. Names are
  831. the same as found in numerous Game Boy hardware documentations.
  832.  
  833.  
  834. 9.3. 'cgb_hardware.i'
  835.  
  836. 'cgb_hardware.i' has all the Color Game Boy hardware register names. Names
  837. are the same as found in numerous Color Game Boy hardware documentations.
  838.  
  839.  
  840. 9.4. 'nintendo_logo.i'
  841.  
  842. Include this file to your projects if you want to run the code on a real
  843. Game Boy. Required data for Nintendo Character Area.
  844.  
  845.  
  846. 9.5. 'pocket_voice.i'
  847.  
  848. Pocket Voice register and command definitions. Based on Bung's Pocket Voice
  849. information.
  850.  
  851.  
  852.  
  853. ------------------------------------------------------------------------------
  854. 10.. Temporary Files
  855. ------------------------------------------------------------------------------
  856.  
  857.  
  858. Note that WLA will generate two temporary files while it works. Make sure
  859. the directories where the temporary files are generated to exist.
  860.  
  861. On Amiga machines these files are placed in T: and are called
  862. "gba_a.tmp" and "gba_b.tmp".
  863.  
  864. On Linux x86 systems these files are placed in /tmp/ and are called
  865. ".gba_a.tmp" and ".gba_b.tmp".
  866.  
  867. On MSDOS x86 machines these files are placed in the working directory and
  868. are called "GBA_A.TMP" and "GBA_B.TMP".
  869.  
  870. So remember not to use more than one WLA process at a time. I will
  871. be honoured to fix this, but it requires a request from a WLA Power
  872. User. ;)
  873.  
  874. When WLA finishes its work these two files are deleted as they serve
  875. of no further use.
  876.  
  877.  
  878.  
  879. ------------------------------------------------------------------------------
  880. 11.. Compiling
  881. ------------------------------------------------------------------------------
  882.  
  883.  
  884. 11.1. Compiling ROM images
  885.  
  886. To compile a ROM image from an asm file use the following:
  887.  
  888. "wla [-v] <ASM FILE> <OUTPUT FILE>"
  889.  
  890. One asm file, one ROM image. Simple, but not very flexible. Compile object
  891. files and link them together in the case of a bigger project.
  892.  
  893. If "-v" is used, WLA displays information about ROM file after a
  894. succesful compile.
  895.  
  896.  
  897. 11.2. Compiling Object Files
  898.  
  899. Version 2.0 of WLA introduced object files. To compile an object file use:
  900.  
  901. "wla [-v] <ASM FILE> -o <OUTPUT FILE>"
  902.  
  903. These object files can be linked together (or with library files) later
  904. with "wlalink".
  905.  
  906. Name object files so that they can be recognized as object files. Normal
  907. suffices are ".o" and ".obj".
  908.  
  909. With object files you can reduce the amount of compiling when editing
  910. small parts of the program. Note also the possibility of using local
  911. labels (starting with "_").
  912.  
  913. Note! When you compile objects, group 1 directives are saved for linking
  914. time, when they are all compared and if they differ, an error message is
  915. shown. It is advisable to use something like an include file to hold all
  916. the group 1 directives for that particular project and include it to every
  917. object file.
  918.  
  919. If you are interested in the WLA object file format, take a look at the
  920. file "object_format.txt" which is included in the release archive.
  921.  
  922. If "-v" is used, WLA displays information about the object file after a
  923. succesful compile.
  924.  
  925.  
  926. 11.3. Compiling Compact Object Files
  927.  
  928. Version 3.0 of WLA introduced compact object files. To compile a compact
  929. object file use:
  930.  
  931. "wla [-v] <ASM FILE> -co <OUTPUT FILE>"
  932.  
  933. Compact object files are just like object files, but the local labels
  934. are made as small as possible by renaming them to short, cryptic strings
  935. like "_a" and "_9e" to save space.
  936.  
  937.  
  938. 11.4. Compiling Library Files
  939.  
  940. Version 2.3 of WLA introduced library files. To compile a library file use:
  941.  
  942. "wla [-v] <ASM FILE> -l <OUTPUT FILE>"
  943.  
  944. Name object files so that they can be recognized as library files. Normal
  945. suffice is ".lib".
  946.  
  947. With library files you can reduce the amount of compiling. Library files
  948. are meant to hold general functions that can be used in different projects.
  949. Note also the possibility of using local labels (starting with "_").
  950.  
  951. If you are interested in the WLA library file format, take a look at the
  952. file "wla_file_formats.txt" which is included in the release archive.
  953.  
  954. If "-v" is used, WLA displays information about the library file after a
  955. succesful compile.
  956.  
  957.  
  958. 11.5. Compiling Compact Library Files
  959.  
  960. Version 3.0 of WLA introduced compact library files. To compile a compact
  961. library file use:
  962.  
  963. "wla [-v] <ASM FILE> -cl <OUTPUT FILE>"
  964.  
  965. Compact library files are just like library files, but the local labels
  966. are made as small as possible by renaming them to short, cryptic strings 
  967. like "_a" and "_9e" to save space.
  968.  
  969.  
  970.  
  971. ------------------------------------------------------------------------------
  972. 12.. Linking
  973. ------------------------------------------------------------------------------
  974.  
  975.  
  976. After you have produced one or more object files and perhaps some library
  977. files, you might want to link them together to produce a ROM image. "wlalink"
  978. is the program you use for that. Here's how you use it:
  979.  
  980. "wlalink [-v] <OBJ1/LIB1> <OBJ2/LIB2> <OBJ3/LIB3> ... -o <OUTPUT FILE>"
  981.  
  982. Make sure all object files have same resolution (same ROM name, same ROM
  983. size...), otherwise WLALINK will fail. And make sure you don't try to insert
  984. libraries into banks that don't exist.
  985.  
  986. If "-v" is used, WLALINK displays information about ROM file after a
  987. succesful linking.
  988.  
  989. Make sure you don't create duplicate labels in different places in Game Boy
  990. memory map as they break the linking loop. Duplicate labels are allowed when
  991. they overlap each other in Game Boy memory. Look at the following example:
  992.  
  993. ...
  994.  
  995. .BANK = 0
  996. .ORG = $150
  997.  
  998.     ...
  999.     LD    A, 1
  1000.     CALL    LOAD_LEVEL
  1001.     ...
  1002.  
  1003. LOAD_LEVEL:
  1004.     LD    HL, $2000
  1005.     LD    (HL), A
  1006.     CALL    INIT_LEVEL
  1007.     RET
  1008.  
  1009. .BANK = 1
  1010. .ORG = 0
  1011.  
  1012. INIT_LEVEL:
  1013.     ...
  1014.     RET
  1015.  
  1016. .BANK = 2
  1017. .ORG = $0
  1018.  
  1019. INIT_LEVEL:
  1020.     ...
  1021.     RET
  1022. ...
  1023.  
  1024.  
  1025.  
  1026. ------------------------------------------------------------------------------
  1027. 13.. Pocket Voice
  1028. ------------------------------------------------------------------------------
  1029.  
  1030.  
  1031. Pocket Voice uses its own MBC. You can enable Pocket Voice mode by selecting
  1032. Pocket Voice cartridge type ($BE). In PV mode bank 0 is 24KB and the rest
  1033. are 8KB. Note that WLA assumes that ROM offset is all the time 0.
  1034. If you use something else as the offset, make sure to compute the jumps by
  1035. hand as WLA cannot do that.
  1036.  
  1037.  
  1038.  
  1039. ------------------------------------------------------------------------------
  1040. 14.. Author
  1041. ------------------------------------------------------------------------------
  1042.  
  1043.  
  1044. Ville Helin, the author of Wzonka-Lad, a Game Boy emulator for the Amiga
  1045. machines. I have 22 years behind me, many more to travel through. I study
  1046. information technology at the Helsinki University of Technology
  1047. (http://www.hut.fi). I like Game Boy (goes without saying), anime soap operas,
  1048. Japanese culture and Kung-Fu.
  1049.  
  1050. email: vhelin@cc.hut.fi
  1051. hpage: http://www.hut.fi/~vhelin
  1052.  
  1053.  
  1054.  
  1055. ------------------------------------------------------------------------------
  1056. 15.. Thanks
  1057. ------------------------------------------------------------------------------
  1058.  
  1059.  
  1060. Thanks to Madonna MkII (Matra Computer Corp.), Gaelan Griffin and Mike Blum
  1061. for reporting bugs in WLA.
  1062.  
  1063. Thanks to Mark Knox and Igor Wronsky for helping me with the MSDOS port!
  1064.  
  1065.  
  1066.  
  1067. ------------------------------------------------------------------------------
  1068. 16.. Future
  1069. ------------------------------------------------------------------------------
  1070.  
  1071.  
  1072. Future enhancements (if I get really inspired):
  1073.  
  1074. - Proper error messages with line numbers.
  1075. - Other optimizations, bug fixes and enhancements.
  1076.  
  1077.  
  1078.  
  1079. ------------------------------------------------------------------------------
  1080. 17.. Support
  1081. ------------------------------------------------------------------------------
  1082.  
  1083.  
  1084. The currently supported systems are MSDOS/x86, AmigaOS/680x0 and Linux/x86.
  1085. If you'd like to see WLA for other platforms/configurations, send me mail
  1086. and we'll see what I can do.
  1087.  
  1088.  
  1089.  
  1090. ------------------------------------------------------------------------------
  1091. 18.. Legal Note
  1092. ------------------------------------------------------------------------------
  1093.  
  1094.  
  1095. WLA GB-Z80 Macro Assembler Copyright 1998-2000 Ville Helin
  1096.  
  1097. I take no responsibility what WLA does on your machine. Remember
  1098. that when using WLA you do it at your own risk.
  1099.  
  1100. WLA is freeware as long as it is used to produce non-commercial software.
  1101.  
  1102. WLA cannot be used in any commercial project without my permission.
  1103.  
  1104. If and when WLA is used in a commercial project, I want something as
  1105. well, like the finished product. ;) Or credits would be nice. ;)
  1106. Something, so I know there are people using WLA.
  1107.  
  1108. WLA may not be put on any CD DISC or HD DISK or any other form of media
  1109. unless I myself grant the premission.
  1110.  
  1111. If I am not contacted before WLA is used in a process that involves money,
  1112. then may the seven drunken Gods strike such a foul business down! If the
  1113. Gods won't do me a favor, I'll ask Monkey King and come and do my Kung-Fu.
  1114.  
  1115. Game Boy and Game Boy Color are copyrighted by Nintendo.
  1116.